docs: contributor and agent guidance, and a precommit alias - #3
Merged
Conversation
This library graduated out of the Fountain umbrella with the template's CI,
release gate and publish workflow, but with none of the guidance that
surrounded it there. Somebody arriving at this repository — a contributor or a
coding agent — had the README's contract and nothing about how to work in the
tree: which checks gate a PR, what the test helper sets up and why, how a
release happens, and which traps this library in particular has.
- CLAUDE.md, read by Claude Code and other agents when a session starts
here: the gate, the coverage threshold and why it is what it is, this
library's test patterns, the release flow, and the things not to do.
- AGENTS.md, a pointer for agents that look for that name instead.
- CONTRIBUTING.md: Apache-2.0 inbound and outbound, the DCO sign-off, what
to run before pushing, and when a change needs a version bump.
- `mix precommit` in mix.exs, running exactly what .github/workflows/ci.yml
runs, in the same order. Until now the only way to run the gate locally
was to reproduce seven steps out of the workflow by hand, including the
two MIX_ENV overrides that are easy to miss.
The alias sets `preferred_envs: [precommit: :test]` to match CI's job-level
MIX_ENV, and shells out with MIX_ENV=dev for dialyzer and hex.build — the same
two overrides CI makes, for the same reasons. The unused-dependency step
compares the lockfile before and after rather than trusting the task's exit
code, because `mix deps.unlock --unused` rewrites mix.lock and exits 0, which
is how an alias can pass while CI fails the same commit on its diff check.
Verified end to end on managoat_sandbox: 236 tests, 0 failures, the coverage
gate met, the package built.
Nothing here changes what the package ships, which is what the no-release
label is for: scripts/release.exs compares mix.exs textually, so a
build-tooling alias reads to it as a consumer-facing change.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Yas72zcnw8CTpxSadda9a9
Signed-off-by: Jake Gaylor <jhgaylor@gmail.com>
jhgaylor
added
the
no-release
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
This library graduated out of the Fountain umbrella with the template's CI, release gate and publish workflow — and none of the guidance that surrounded it there. Somebody arriving at this repository, a contributor or a coding agent, got the README's contract and nothing about how to work in the tree: which checks gate a PR, what the test helper sets up and why, how a release happens, and which traps this library in particular has.
What this adds
CLAUDE.mdtest/test_helper.exssets up and why; the release flow; and the things not to do, with the traps specific to this library.AGENTS.mdCLAUDE.md, for agents that look for that filename instead.CONTRIBUTING.mdmix.exsprecommitalias.CLAUDE.mddefers toREADME.mdrather than restating it: the README stays the normative description of what the library does, andCLAUDE.mdcovers working in the repository.mix precommitRuns what
.github/workflows/ci.ymlruns, in the same order: the unused-dependency check,format --check-formatted,compile --warnings-as-errors,credo --strict, dialyzer,test --cover,hex.build. Until now the only way to run the gate locally was to reproduce seven steps out of the workflow by hand, including two environment overrides that are easy to miss.Four details worth a reviewer's eye:
def clisetspreferred_envs: [precommit: :test], matching CI's job-levelMIX_ENV: test.hex.buildshell out withMIX_ENV=dev— the same two overrides CI makes, for the same reason: dialyzer analyses the shipped code, and the test env would pull test-only deps into the analysis and into the cached PLT.mix.lockbefore and after rather than trusting the task's exit code.mix deps.unlock --unusedrewrites the lockfile and exits 0, so the naive version passes while CI fails the same commit on itsgit diff --exit-code mix.lock.hex.buildwrites its tarball to a temp directory. It is a check, not an artifact, and nothing should have to gitignore it.Verified end to end on
managoat_sandbox: 236 tests, 0 failures, coverage gate met, package built, exit 0.Why the
no-releaselabelNothing here changes what the package ships.
scripts/release.exscomparesmix.exstextually —consumer_facing/1strips comments andonly: :dev/:testdependency lines, but not an aliases block — so a build-tooling alias reads to the gate as a consumer-facing change. This is the documented exception the label exists for.Notes
One of a set of PRs across all nine
managoat_*libraries. The structure is shared; the per-library content inCLAUDE.md(coverage rationale, test patterns, traps) is written per repository.templates/managoat-libraryin Fountain is deliberately not updated in this pass, so a future graduation will not inherit this yet — worth a follow-up.Separately: the
no-releaselabel did not exist in any of the nine repositories, althoughscripts/graduate-library.shstep 5 creates it as part of graduation. It has been created here.🤖 Generated with Claude Code
https://claude.ai/code/session_01Yas72zcnw8CTpxSadda9a9